The Very Best of Atari Inside/The Very Best of Atari Inside 1.iso/sharew/accs/cal47/cal47.doc

Text File | 1991-03-16 | 18.6 KB | 349 lines

                         Cal: The Calendar Program v4.7
                        Copyright (c)1991 by Bill Aycock


Ever forgotten your anniversary or your kid's birthday? Missed a TV show
because you didn't remember what day it was on? Went to work an hour late when
you forgot to reset your clock for Daylight Savings Time? If this has happened
to you, Cal may be able to help!

Cal is a calendar program with a difference - it lets you attach 'events' to
any day of the year, either by date or according to a day's position in the
month. When Cal loads, it reads the current date from your system clock and
checks to see if any significant events are scheduled for the day. If so, Cal
displays an alert that shows you the day's events. (When Cal loads as an ACC,
it dings the system bell if a significant event is scheduled.)

Also included in this ARC file is a new version of CalShow, an AUTO program
that will read the events from Cal, display the next 22 events on screen, then
pause so you can easily see what's on tap for the next couple weeks. This
should give you plenty of time to plan for upcoming events! (Note, you must
replace your old version of CalShow with this version. See the separate CalShow
doc file for more information.)

Cal comes ready to go, pre-configured with seven dozen commonplace and
obscure events. To use Cal, either install it as a desk accessory in the normal
fashion, or just run it as a program. Cal uses around 37K of memory, and runs
on any ST or TT in any resolution.


* The main screen: looking at a specific month and year


Most of the main screen is taken up with the calendar display. There are
twelve small buttons under this display that allow you to see the calendar of
any month in the year; just click the appropriate button. If you double-click
one of these buttons, the calendar display will change to that month of the
current year.

To the right of the calendar is a box that tells which month and year the
calendar is showing. The six buttons under this box let you skip forward and
back in one, ten, or hundred-year increments. (You can double-click on the
hundreds buttons to move a thousand years at a time.) Also, if you click on the
year number you can enter a specific year for Cal to display.

Underneath the six year buttons are two small words, PREV and NEXT. You can
click on these words to move forward or back one month at a time. The display
will wrap around the end of a year; for example, if you are looking at December
and click NEXT, you'll see January of the following year.

Three large buttons appear at the bottom of the main screen. If you click the
Today button while looking at the current month, Cal will display today's Day
Alert, showing you the day of the year and any events scheduled for today. If
you're looking at a different month when you click Today, Cal will simply
display the current month. The Browse button will take you to the Browse dialog
(see below for more information on browsing events). To exit Cal, click the
Exit button or simply hit Return.


* Different types of days


The days in the calendar display come in four varieties. If Cal is showing
the calendar of the current month and year, then today's date will be
outlined. Days which are highlighted (i.e., white numbers on a black
background) indicate that special events are scheduled on those days. Normal
black-on-white numbers are simply days of the month which do not have events
attached. Days in the preceding and following months are grayed out.


* Looking at a specific day and its events


To look at a specific day more closely, simply click on its date in the
calendar. This brings up the Day Alert screen. The top of this screen displays
the day of the week and the date, the day of the year, and how many days are
left in the year. Underneath this is a box which tells you of any events
scheduled on the day. Up to four messages can appear in this box. If there are
more than four events scheduled for the day, you can click the button labelled
"next page" to see the next group of four events. The list of events 'wraps
around' at the end. For example, if you have six events for one day, the first
four are shown first. Click "next page" and Cal will show you the fifth and
sixth events, plus the first two.

Note: Cal will display at most 50 events for a single day, only 45 of which
can be date events. If you find that this is too limiting, split your events
between two copies of Cal.

To change one of the day's events (or add a new event for the day), simply
click directly on the text of a message. If you do so, you'll move to the Edit
dialog with that particular event selected. (See the next section for more
information on editing events.)

You can click the Exit button (or hit Return) to return to the main calendar
display from the Day Alert.


* Entering, editing, and deleting events


The Edit dialog allows you to edit existing events or enter new events. This
dialog has two separate 'modes' - you may edit events either By Date or By
Position. The two large buttons at the top of the screen let you switch between
these two modes. The only difference between the two is that in Date mode, you
see a space where you can enter a specific day of the month and year, but in
Position mode you see two rows of buttons that let you specify a particular
position in the month (e.g., the fourth Thursday). Both modes include buttons
for you to select a particular month or specify that an event is 'significant',
a space for you to enter a message for an event, and a number of action buttons
across the bottom of the screen.

There are two ways to get to the Edit dialog: you can click on the text of a
message from the Day Alert, or you can click the Edit button from the Browse
dialog (more on that later). If you enter the Edit dialog by selecting a date
event, you start out in Date mode; if you select a positional event instead,
then you start in Position mode. In any case, the Edit dialog is preset to the
day you were looking at.

To add a new event, first indicate when the event occurs by selecting a month
and entering a date or selecting a position. Then click the By Date or By
Position button at the top of the screen to have Cal update the display. Cal
will look at the date or position you entered and cycle through all the events
scheduled for that day. This step is especially important before you erase or
replace an event; if you select a different month or day, always let Cal know
by clicking one of these buttons, or you may erase or replace the wrong event!

After you've selected the right schedule, decide if your new event is
'significant' or not, and select the proper significance button (to the left of
the month buttons). These buttons won't affect how Cal handles the event, but
if an event is NOT significant, then CalShow won't normally display the event
in its list. (You can tell CalShow to include the event by including the "a"
command-line option; see the CalShow documentation for more information.)

If you are in Date mode, you can tell Cal that an event will only occur once
by typing a year in the space provided. This can be handy for remembering a
meeting, dentist appointment, or other similar event. Once the event has
expired (i.e., when the event's date has passed), Cal will automatically erase
the event for you. (You can also configure Cal to ask you before it erases an
expired event, or to do nothing to expired events - see the section about
One-Time events below.) If you define a one-time event, it will only show up on
the Day Alert when you're looking at that specific year. (All events, including
one-time events, will still show up when you browse.)

Once you've selected the right schedule and significance buttons, add a new
event by typing a short message in the space provided. When you're done, click
the Add button to store your event in memory. To _replace_ an event with a new
message, click the Replace button (marked "repl") instead.

If you want to erase an event, click the Erase button at the bottom of the
screen. This brings up a dialog that lets you erase the event you're editing,
all events in that month, or all the events stored in Cal. Select the
appropriate button, then click the Erase Events button, or the Cancel button if
you change your mind. If you choose to erase all events or an entire month's
events, you'll be asked to verify your decision before the events are erased.

When you've finished editing the events, click the Save button at the bottom
of the screen - this gives you a chance to locate the Cal program file and save
your changes. When you've finished saving, click the Exit button (or hit
Return) to exit the Edit dialog. (If you prefer, you don't have to save your
changes as soon as you finish editing events. If you make any changes to events
or to your Cal setup, then try to exit Cal without having saved the changes,
you'll see an alert giving you the chance to "save, resume, or exit". Select
"save" if you want to store your changes into Cal, "exit" if you want to exit
Cal without saving the changes you made, or "resume"  to return to the main
calendar screen.)

Note: if you upgrade to a newer version of Cal, you WON'T need to type in all
your events again! Simply run your old version of Cal, go to the Edit screen,
and select Save. When the file selector comes up, select the new version of Cal
and save your events. Side note: one of the items Cal saves is the title bar
and Desk menu entry... this means that when you run the new copy of Cal, the
old title bar will show up. Unless you've customized your title, you may want
to update the title to show the new version number; see the section below on
customizing Cal for information on how to do this.


* Browsing through the events


To inspect all the events stored in Cal, click the Browse button from the
main calendar screen. This will take you to the Browse dialog, where you can
look through your events starting with the month shown on the calendar screen.
Events are displayed in chronological order, with all the positional events for
a month shown before the date events. If a number of events are scheduled for
the same day, they are shown in alphabetical order.

The top of the Browse dialog tells you how many of each type of event there
are and the total number of events. Under that is a box that lists which event
you're looking at, whether it's a Date event, a one-time event, or a Positional
event, and when the event occurs. The next box displays the message for the
current event.

Under this display are two rows of buttons. Four of the buttons let you move
through the events on file - First and Last take you to the beginning or end of
the events, and Next and Previous move you forward or back one event at a time.
You can double-click the Next and Previous buttons to move ten events at a
time. Note: the Next button is the default button, so you can move ahead one
event by simply hitting Return. To exit the Browse dialog, you must either
click the EXIT button or hold down the Alternate key when you press Return.

The Find button gives you a chance to enter a character string and search
through the events to find one which contains that string. The search starts at
the event following the one you're browsing, wraps around to the beginning, and
ends back at the current event if no match is found. By default, the search is
not case-sensitive; if you want to change this, select the "case sensitive"
button. You may also restrict the search to a particular type of event (i.e., a
positional, one-time, or recurring event or some combination) or to significant
events only; to do so, select the appropriate buttons in the lower box.

The Erase button lets you remove the event you're currently browsing, one
month's events, or all events. The Edit button takes you to the Edit dialog
with everything preset to the event you're browsing.


* One-Time events


When Cal starts up, it reads the current date from your system's clock. If
you've scheduled a one-time event for a particular date and year, and Cal finds
that that date has passed, it realizes that the event has 'expired'. When this
occurs, Cal will display the Expired Event alert.

Cal shows you the event and asks if you want it erased or converted to a
yearly event. Select the appropriate button, then click the Accept button.
If you'd rather wait until later to decide, you can click Skip to move on to
the next expired event. You can also click the Cancel button to skip over all
expired events at once. Any expired events that you skip will still be waiting
for you next time you start Cal.

If you prefer, you can have Cal automatically erase expired events without
asking about each one, or do nothing when an event expires. To set this up, use
the Preferences dialog to customize Cal's behaviour.

Note: when Cal erases expired events for you automatically, it sets a flag to
show that your setup has changed. If you try to exit Cal without having saved
your setup after this occurs, you'll see the alert telling you that you need to
save the setup. If you see this alert but you haven't changed any events or
preferences, don't be alarmed; it's due to expired events being erased.


* Preferences: Customizing Cal


You have the option of customizing several aspects of Cal's behaviour. You
can specify the Desk menu entry Cal will use when running as an accessory,
change how Cal handles expired events, and decide whether or not Cal draws
grow/shrink boxes or displays alerts when you add, replace, or erase events.

To change any of these items, click on the large title bar at the top of the
main calendar screen. When the dialog appears, select the radio buttons for
the features you want activated. If you wish, type in a new Desk menu entry.
When you finish selecting your preferences, click the "accept" button or just
hit Return. If you decide not to make any changes, click the "cancel" button
to return to the main screen.

After you change any of these settings, be sure to save your new setup,
either from the Edit dialog or when exiting the program.


* Technical stuff


CalShow can provide a simple printout of upcoming events, but there is
currently no way to print out a pretty, formatted list. In case someone wants
to write such a program, I'm providing the format of Cal's event database. The
following data is stored in Cal, starting at an offset of $36 bytes from the
beginning of the file...

    4 bytes     "ca31"  identifier, shows this is Cal
    1 long       6000   the current amount of space for event storage
    14 bytes     ...    the last filename used when saving data
    1 word       ...    the offset from the start of the message area
                          to the beginning of the unused part
    6000 bytes   ...    the message area itself (see below)
    6 bytes      ...    reserved; flags, etc.
    18 bytes     ...    the current title bar/Desk menu entry

Each event is stored in the message area, and has this format:

      offset 0   word   offset to next event entry
      offset 2   byte   event date (1..31) or zero if a positional event
      offset 3   byte   month of event (1..12)
  NOTE: the high bit of the month is SET if the event is NOT significant
      offset 4   byte   week position (0-4=weeks 1-5, 5=last, 6=each)
      offset 5   byte   weekday (0=Sunday, 1=Monday ... 6=Saturday)
  OR: offset 4   word   year for a one-time date event
      offset 6   ....   the actual message, a null-terminated string

If anyone decides to write a pretty-print program for upcoming events, please
let me know!


* Credits and a postcardware plea


Cal and CalShow were written completely in assembly language using the HiSoft
DevpacST assembler. Cal's resource was created with WERCS, and converted to
assembly code using a program written by Carl Barron. Thanks to the following
people for beta testing and some great suggestions: Robert Birmingham, Keith
Joins, Jimmy Long, Jim Ness, Rob Rasmussen, Ray Mattera, Bob Schulze, Jody
Golick, Thomas Miller, Phil Vaughan, Malcolm McMahon, Mike Squire, Mickey Boyd

The calendar routine I use in Cal was based on Zeller's Congruence, which
explains a simple way to calculate the day of the week for a given date without
resorting to a lookup table. Articles dealing with this subject appeared in
Computer Language Magazine, March and December 1988. (The articles were
helpful, although they included a couple of typographical errors. :-) Also note
that the modern calendar wasn't invented until the 1580s, something to keep in
mind if you're poking around in the dim and distant past <grin>.

Please let me know if you use this program!!! Comments, bug reports,
suggestions, and requests are all welcome. If you need a version of Cal with
more storage room for events, I'd be glad to assemble one for you. Donations
are gratefully accepted - but even if you don't want to contribute, please
send me a postcard at the address below!


      Bill Aycock
      2310 North Elm Street
      Greensboro, NC 27408

      Compuserve ID: 76703,4061
      March 17, 1991

-------------------------------
version history:
v4.7: added support for significant/non-significant events
v4.5: added multiple positional events; when saving setup, file selector now
      defaults to path Cal loaded from; allow more events on single day; added
      code to help guard against unusual March start date problem
v4.4: added option to supress add/replace/erase event alerts; added case
      sensitive search, retains search string between searches
v4.3: fixed a logic bug occurring when exiting Cal in some circumstances;
      added keyboard exit from Browse screen
v4.2: added Replace button in Edit; added option to ignore expired events;
      added type filters to Find function; changed Browse logic
v4.1: added grow/shrink box support; added leap-year check for one-time
      events on Feb 29; skip saving duplicate events; sundry other tweaks
v4.0: added multiple events on the same date; added alphabetic sort; added
      one-time events and expired-event handling; various other tweaks
v3.5: fixed filepath setup for standard GEM file selector problem
v3.4: fixed logic error in CalShow; enabled 'last' week position button
v3.3: fixed obscure bug in Find function; redesigned Browse screen and Today
      button logic; added Prev and Next month buttons; added option to save
      changed setup when exiting
v3.2: fixed occasional bus errors after erasing events and then browsing;
      included CalShow for bootup reminders
v3.1: first released version supporting events
v2.0: final calendar-only version